core module

This package contains core modules and classes for representing force fields, internal coodinates and mammoth parameters.

The core module of Mammoth implements base classes to represent core objects used in the package such as internal coordinates, molecule or force fields.

Force fields representations

This module contains classes that represents a complete force fields and provides methods in order to export these forcefields in various format as input for molecular dynamics programs.

• ForceField is a general base class

• the ClassicalForceField class represents a classical force field defined from

  a list of bonds, angles, dihedrals, impropers and non-bonded terms.

class mammoth.core.forcefield.ForceField(molecule)

A general class to store a Forcefield

Parameters:molecule (Molecule) – The molecule associated to the force ForceField

class mammoth.core.forcefield.ClassicalForceField(molecule, bonds=None, angles=None, dihedrals=None, impropers=None, charges=None)

A class which represents a classical force field such as Charm, AMBER, or Gromos.

All data needed to build the topology of the forcefield are mandatory. Default values are empty lists.

Parameters:

• molecule (Molecule) – the Molecule
• bonds (Bond) – List of bonds
• angles (Angle) – List of angles
• dihedrals (Dihedrals) – List of dihedral angles
• impropers (Improper) – List of improper torsions
• charges (list) – atomic charges

as_dict(params='all')

Return a serializable dict to export whole or part of the force field to a json file. Look at monty.json and MSNoable class for the future. The approach is the one followed by pymatgen.

Parameters:params (list or string) – List of forcefield component to be exported among ‘bonds’, ‘angles’, ‘dihedrals’, ‘impropers’, ‘charges’, ‘vdw’. If ‘all’, all the forcefield is return.

export_lammps_data(filename=None)

Export the force field for LAMMPS

Internal coordinates

This module contains classes that represents the internal coordinates of a molecular systems.

All classes inherit from the InternalCoord class.

class mammoth.core.internal_coords.Bond(*args, **kwargs)

A class that represents a bond

Store internal coordinates data:

Parameters:

• atoms (list) – list of atom indexes
• value (float) – equilibrium value of the coordinates
• frc_cste (float) – force constant value
• elements (list) – list of elements, either string or pymatgen.Element

class mammoth.core.internal_coords.Angle(*args, **kwargs)

A class that represents an angle

Store internal coordinates data:

Parameters:

• atoms (list) – list of atom indexes
• value (float) – equilibrium value of the coordinates
• frc_cste (float) – force constant value
• elements (list) – list of elements, either string or pymatgen.Element

class mammoth.core.internal_coords.Dihedral(atoms, value, frc_cste, elements, periodicity=None, potential='parabolic')

A class that represents an dihedral angle

Store internal coordinates data:

Parameters:

• atoms (list) – list of atom indexes
• value (float) – equilibrium value of the coordinates
• frc_cste (float) – force constant value
• elements (list) – list of elements, either string or pymatgen.Element
• periodicity (int) – periodicity in case of harmonic or sinusoidal potential
• potential (str) – functional form of the potential energy

as_dict()

Return a serializable dict to export the internal coordinate to a json file. Look at monty.json and MSNoable class for the future. The approach is the one followed by pymatgen.

compute_periodicity(nnj, nnk)

Compute the periodicity of a dihedral angle according to the procedure proposed by Nilson et al. (Acta Cryst 2003 D59, 274 - 289).

The dihedral angle is supposed to be a torsion around atom j and atom k which are bounded together and correspond to the second and the third atoms of the self.atoms field of the dihedral.

i        l
 \      /
  j -- k

Parameters:

• nvoisj (int) – number of neighbors of atom j
• nvoisk (int) – number of neighbors of atom k

Returns:

The periodicity (int)

classmethod from_dict(d)

Return a dihedral object from a dictionnary.

Parameters:d (dict) –

A dict representation of the dihedral angle such as

{“atoms”: (1, 2, 3, 4), “value”: 120.32, “frc_cste”: 4.7,

”elements”: [“H”, “C”, “N”, “H”], “potential”: “harmonic”, “periodicity”: 3}

Returns:Dihedral object

class mammoth.core.internal_coords.Improper(*args, **kwargs)

A class that represents an improper dihedral angle

Store internal coordinates data:

Parameters:

• atoms (list) – list of atom indexes
• value (float) – equilibrium value of the coordinates
• frc_cste (float) – force constant value
• elements (list) – list of elements, either string or pymatgen.Element

Molecule class

This module provides a subclass of the pymatgen.core.structure.Molecule class in order to add new attributes dedicated to the forcefield factory.

class mammoth.core.molecule.Molecule(species, coords, charge=0, spin_multiplicity=None, validate_proximity=False, site_properties=None, bond_orders=None, at_charges=None, hessian=None, grad=None)

A molecule object inherited from the [pymatgen package](http://pymatgen.org) with new attributes dedicated to the force field factory.

Creates a MutableMolecule.

Parameters:

• species – list of atomic species. Possible kinds of input include a list of dict of elements/species and occupancies, a List of elements/specie specified as actual Element/Specie, Strings (“Fe”, “Fe2+”) or atomic numbers (1,56).
• coords (3x1 array) – list of cartesian coordinates of each species.
• charge (float) – Charge for the molecule. Defaults to 0.
• spin_multiplicity (int) – Spin multiplicity for molecule. Defaults to None, which means that the spin multiplicity is set to 1 if the molecule has no unpaired electrons and to 2 if there are unpaired electrons.
• validate_proximity (bool) – Whether to check if there are sites that are less than 1 Ang apart. Defaults to False.
• site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.
• at_charges (list) – atomic charges of sites in the molecule
• bond_orders (dict) – Dict of atom pairs with a bond order value.
• hessian (3N x 3N array) – The hessian matrix of the molecule
• grad (3N x 3 array) – The (last) gradient of the molecule

get_atoms_in_bond(pair)

return the bond order value from the atom index

get_bo_value(pair)

return the bond order value from the atom index